home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 551-575 / disk_570 / view / ascii.doc < prev    next >
Text File  |  1992-05-06  |  12KB  |  451 lines
  1.  
  2. TABLE OF CONTENTS
  3.  
  4. ascii.s/BOpen
  5. ascii.s/BClose
  6. ascii.s/BIoErr
  7. ascii.s/BGetC
  8. ascii.s/BPutC
  9. ascii.s/AllocAscii
  10. ascii.s/FreeAscii
  11. ascii.s/BGetS
  12. ascii.s/BPutS
  13. ascii.s/FirstOccurrence
  14. ascii.s/NextOccurrence
  15. ascii.s/PreviousOccurrence
  16. ascii.s/FindFrom
  17.  
  18.  
  19. ascii.s/BOpen                                                  ascii.s/BOpen
  20.  
  21.   NAME
  22.     BOpen -- open a file for bufferd IO.
  23.  
  24.   SYNOPSYS
  25.     file = BOpen( name, accesmode )
  26.  
  27.     struct BuffIO *file;
  28.     char          *name;
  29.     ULONG          accessmode;
  30.  
  31.   FUNCTION
  32.     To setup a "BuffIO" file handle and to open the file for you.
  33.  
  34.   INPUTS
  35.     name       - A pointer to a null  terminated string which  should be the
  36.                  full AmigaDOS name of the file you want to open.
  37.     accessmode - The acces-mode of the file you want to open. Currently only
  38.                  "MODE_OLDFILE" and "MODE_NEWFILE" are supported.
  39.  
  40.   RESULT
  41.     file will be a pointer to the "BuffIO" file handle  or null if something
  42.     went wrong.
  43.  
  44.   BUGS
  45.     None known.
  46.  
  47.   SEE ALSO
  48.     dos.library/Open()
  49.  
  50.  
  51. ascii.s/BClose                                                ascii.s/BClose
  52.  
  53.   NAME
  54.     BClose -- close a "BuffIO" file handle.
  55.  
  56.   SYNOPSYS
  57.     error = BClose( file )
  58.  
  59.     LONG           error;
  60.     struct BuffIO *file;
  61.  
  62.   FUNCTION
  63.     To flush it's internal buffer  and close the file.  Then deallocate  the
  64.     "BuffIO" file handle.
  65.  
  66.   INPUTS
  67.     file - A pointer to the "BuffIO" file handle which you want to close.
  68.  
  69.   RESULT
  70.     The return code needs  only to  be checked when  the handle was  used to
  71.     write to (MODE_NEWFILE). This is because this  routines writes all  data
  72.     left in the buffer to the file before it's closed.
  73.  
  74.   BUGS
  75.     None known.
  76.  
  77.   SEE ALSO
  78.     dos.library/Close()
  79.  
  80.  
  81. ascii.s/BIoErr                                                ascii.s/BIoErr
  82.  
  83.   NAME
  84.     BIoErr -- determine the last error of the file.
  85.  
  86.   SYNOPSYS
  87.     error = BIoErr( file )
  88.  
  89.     LONG           error;
  90.     struct BuffIO *file;
  91.  
  92.   FUNCTION
  93.     To take the last error from the "BuffIO"  file handle and  return it  to
  94.     you.
  95.  
  96.   INPUTS
  97.     file - A pointer to the "BuffIO" file handle of which you  want to  know
  98.            it's error status.
  99.  
  100.   RESULT
  101.     error will be one of the following values :
  102.  
  103.       ASE_OK          - everything OK
  104.       ASE_EOF         - everything OK but at end-of-file.
  105.       ASE_NOMEM       - out of memory
  106.       ASE_READ        - read error
  107.       ASE_WRITE       - write error
  108.       ASE_NOFILE      - obsolete (will never happen!)
  109.       ASE_FILETYPE    - tryed to write to MODE_OLDFILE or viceversa
  110.  
  111.   BUGS
  112.     None known.
  113.  
  114.  
  115. ascii.s/BGetC                                                  ascii.s/BGetC
  116.  
  117.   NAME
  118.     BGetC -- get one byte from a "BuffIO" file handle.
  119.  
  120.   SYNOPSYS
  121.     byte = BGetC( file )
  122.  
  123.     LONG           byte;
  124.     struct BuffIO *file;
  125.  
  126.   FUNCTION
  127.     To get one byte from the "BuffIO" file handle.  If there arn't any bytes
  128.     left in the buffer it will try to fill the buffer with data first.
  129.  
  130.   INPUTS
  131.     file - A pointer to the "BuffIO" handle you want to get one byte from.
  132.  
  133.   RESULT
  134.     byte should be the byte from the "BuffIO" handle (0-255). If the routine
  135.     returned ASE_EOF you should make a call to "BIoErr()" to check wether or
  136.     not there was an error.
  137.  
  138.   BUGS
  139.     None known.
  140.  
  141.   SEE ALSO
  142.     ascii.s/BIoErr()
  143.  
  144.  
  145. ascii.s/BPutC                                                  ascii.s/BPutC
  146.  
  147.   NAME
  148.     BPutC -- write one byte to a "BuffIO" file handle.
  149.  
  150.   SYNOPSYS
  151.     error = BPutC( file, byte )
  152.  
  153.     LONG           error;
  154.     struct BuffIO *file;
  155.     ULONG          byte;
  156.  
  157.   FUNCTION
  158.     To put a byte in the "BuffIO" handle it's buffer. If the buffer was full
  159.     it first writes the  data  in the  buffer to the  file and then puts the
  160.     byte in the buffer.
  161.  
  162.   INPUTS
  163.     file - A pointer to the "BuffIO" file handle to  which you want to write
  164.            a byte.
  165.     byte - The byte (0-255) you want to write.
  166.  
  167.   RESULT
  168.     Although most of the times "error" will read ASE_OK you should check the
  169.     return code once in a while to see if the writing of  the buffer to  the
  170.     file went OK.
  171.  
  172.   BUGS
  173.     None known.
  174.  
  175.  
  176. ascii.s/AllocAscii                                        ascii.s/AllocAscii
  177.  
  178.   NAME
  179.     AllocAscii -- allocate a "AsciiText" structure.
  180.  
  181.   SYNOPSYS
  182.     ascii = AllocAscii( tabsize, maxchars, flags )
  183.  
  184.     struct AsciiText  *ascii;
  185.     ULONG              tabsize;
  186.     ULONG              maxchars;
  187.     ULONG              flags;
  188.  
  189.   FUNCTION
  190.     To allocate an  "AsciiText"  structure and  to initialize it  with  your
  191.     preferred settings.
  192.  
  193.   INPUTS
  194.     tabsize  - The size of one tabstop.
  195.     maxchars - The  maximum  amount  of  characters allowed  in one  line. A
  196.                minimum of 5 and a maximum of 256 are allowed here.
  197.     flags    - Flag bits. These two are allowed here :
  198.  
  199.                   ATF_SkipEsc    - This tells "BGetS"  not to  count  escape
  200.                                    sequences as printable characters.
  201.                   ATF_TabConvert - This tells "BGetS" to convert  TABS  into
  202.                                    blanks.
  203.  
  204.   RESULT
  205.     ascii will be a pointer to an AsciiText structure or  null if there  the
  206.     structure could not be allocated.
  207.  
  208.   BUGS
  209.     None known.
  210.  
  211.  
  212. ascii.s/FreeAscii                                          ascii.s/FreeAscii
  213.  
  214.   NAME
  215.     FreeAscii -- deallocate an AsciiText structure.
  216.  
  217.   SYNOPSYS
  218.     FreeAscii( ascii )
  219.  
  220.     struct AsciiText  *ascii;
  221.  
  222.   FUNCTION
  223.     To deallocate the memory of the text in the AsciiText structure  and the
  224.     memory of the AsciiText structure itself.
  225.  
  226.   INPUTS
  227.     ascii - A pointer to the AsciiText structure you want to deallocate.
  228.  
  229.   BUGS
  230.     None known.
  231.  
  232.  
  233. ascii.s/BGetS                                                  ascii.s/BGetS
  234.  
  235.   NAME
  236.     BGetS -- get one line of text from the "BuffIO" handle.
  237.  
  238.   SYNOPSYS
  239.     line = BGetS( file, ascii );
  240.  
  241.     struct Line       *line;
  242.     struct BuffIO     *file;
  243.     struct AsciiText  *ascii;
  244.  
  245.   FUNCTION
  246.     To allocate a line structure and read a complete text line.  If the line
  247.     contains more bytes than specified by you with "AllocAscii()"  the  line
  248.     will be truncated with a NEWLINE and the LNF_Split flag will  be set  in
  249.     the line. This means that such a line contains "line->Size - 1" bytes of
  250.     actual data and one inserted NEWLINE.
  251.  
  252.   INPUTS
  253.     file  - A pointer to the BuffIO  file handle in from which the line will
  254.             be read.
  255.     ascii - A pointer to the AsciiText structure in which the memory for the
  256.             line will be allocated.
  257.  
  258.   RESULT
  259.     line will  be a  pointer to  the  Line  structure or null if the routine
  260.     failed. NOTE: The line will not be added to  the text itself.  You  must
  261.     "AddTail(ascii,line)" it to do so. Do NOT add a line  allocated  in  one
  262.     AsciiText structure to another AsciiText structure!
  263.  
  264.   BUGS
  265.     The routine chokes when the "ATF_SkipEsc" flag is set and the  line  has
  266.     more than "MAXLINE" characters + escape sequences in it.  If this is the
  267.     case it will overflow it's internal buffer.
  268.  
  269.   SEE ALSO
  270.     ascii.s/AllocAscii()
  271.  
  272.  
  273. ascii.s/BPutS                                                  ascii.s/BPutS
  274.  
  275.   NAME
  276.     BPutS -- write one line of text to a "BuffIO" handle.
  277.  
  278.   SYNOPSYS
  279.     error = BPutS( file, line )
  280.  
  281.     LONG           error;
  282.     struct BuffIO *file;
  283.     struct Line   *line;
  284.  
  285.   FUNCTION
  286.     Write out the specified  line to the "BuffIO"  file handle.  The routine
  287.     writes "line->Size" bytes of data from normal lines and "line->Size - 1"
  288.     bytes of data from lines with the LNF_Split flag set.
  289.  
  290.   INPUTS
  291.     file - A pointer  to the "BuffIO"  file  handle  to which  the  line  is
  292.            written.
  293.     line - A pointer to the "Line" structure which must be written.
  294.  
  295.   RESULT
  296.     error is ASE_OK if everything went OK or something else if an  error has
  297.     occurred.
  298.  
  299.   BUGS
  300.     None known.
  301.  
  302.   SEE ALSO
  303.     ascii.s/BIoErr()
  304.  
  305.  
  306. ascii.s/FirstOccurrence                              ascii.s/FirstOccurrence
  307.  
  308.   NAME
  309.     FirstOccurrence -- find the first occurrence of a string in a text.
  310.  
  311.   SYNOPSYS
  312.     found = FirstOccurrence( ascii, string, strscn, case )
  313.  
  314.     LONG               found;
  315.     struct AsciiText  *ascii;
  316.     UBYTE             *string;
  317.     struct StringScan *strscn;
  318.     LONG               case;
  319.  
  320.   FUNCTION
  321.     To find the first occurrence of a specific string in a text. The routine
  322.     starts to look from the first line in the text.  This  also set's up the
  323.     the StringScan structure for further usage by Next/PreviousOccurrence().
  324.     This routine must be called  BEFORE Next/PreviousOccurence() are called.
  325.  
  326.  
  327.   INPUTS
  328.     ascii  - A pointer to the AsciiText structure in which the  routine must
  329.              look for the string.
  330.     string - A pointer to the null terminated  string the routine  must look
  331.              for.
  332.     strscn - A pointer to a StringScan structure in which the routine  keeps
  333.              track of the search.
  334.     case   - This  should be TRUE if  you want a  case sensitive  search and
  335.              FALSE if not.
  336.  
  337.   RESULT
  338.     found  reads  TRUE if  the  routine  has found the string looked for and
  339.     FALSE if not.  If  the  routine  returns  TRUE  the StringScan structure
  340.     contains the specific position where it has found the string.
  341.  
  342.   BUGS
  343.     None known.
  344.  
  345.   SEE ALSO
  346.     ascii.s/NextOccurrence(), ascii.s/PreviousOccurrence()
  347.     ascii.s/FindFrom()
  348.  
  349.  
  350. ascii.s/NextOccurrence                                 ascii.s/NextOccurence
  351.  
  352.   NAME
  353.     NextOccurrence -- find the next occurence of a string in a text.
  354.  
  355.   SYNOPSYS
  356.     found = NextOccurrence( strscn, case )
  357.  
  358.     LONG               found;
  359.     struct StringScan *strscn;
  360.     LONG               case;
  361.  
  362.   FUNCTION
  363.     To find the next occurence of a string in a text.  The routine starts to
  364.     look from the last  position it  has found  the string.
  365.  
  366.   INPUTS
  367.     strscn - A  pointer  to  the  StringScan  structure  which was  used  to
  368.              find the first occurrence of the string.
  369.     case   - See ascii.s/FirstOccurrence()
  370.  
  371.   RESULT
  372.     See ascii.c/FirstOccurrence()
  373.  
  374.   BUGS
  375.     None known.
  376.  
  377.   SEE ALSO
  378.     ascii.s/FirstOccurrence(), ascii.s/FindFrom()
  379.  
  380.  
  381. ascii.s/PreviousOccurrence                         ascii.s/PreviousOccurence
  382.  
  383.   NAME
  384.     PreviousOccurrence -- find the previous occurence of a string in a text.
  385.  
  386.   SYNOPSYS
  387.     found = PreviousOccurrence( strscn, case )
  388.  
  389.     LONG               found;
  390.     struct StringScan *strscn;
  391.     LONG               case;
  392.  
  393.   FUNCTION
  394.     To find the previous occurence of a string in a text. The routine starts
  395.     to look from the last position it has found  the string.
  396.  
  397.   INPUTS
  398.     strscn - A  pointer  to  the  StringScan  structure  which was  used  to
  399.              find the first occurrence of the string.
  400.     case   - See ascii.s/FirstOccurrence()
  401.  
  402.   RESULT
  403.     See ascii.c/FirstOccurrence()
  404.  
  405.   BUGS
  406.     None known.
  407.  
  408.   SEE ALSO
  409.     ascii.s/FirstOccurrence(), ascii.s/FindFrom()
  410.  
  411.  
  412. ascii.s/FindFrom                                            ascii.s/FindFrom
  413.  
  414.   NAME
  415.     FindFrom -- find the first occurrence of a string in a text.
  416.  
  417.   SYNOPSYS
  418.     found = FindFrom( ascii, string, strscn, line, case )
  419.  
  420.     LONG               found;
  421.     struct AsciiText  *ascii;
  422.     UBYTE             *string;
  423.     struct StringScan *strscn;
  424.     struct Line       *line;
  425.     LONG               case;
  426.  
  427.   FUNCTION
  428.     This routine does the same thing as  FirstOccurrence exept  that you can
  429.     specify the line where it must start the search.
  430.  
  431.   INPUTS
  432.     ascii  - See FirstOccurence.
  433.     string - See FirstOccurence.
  434.     strscn - See FirstOccurence.
  435.     line   - A pointer to the "Line" structure from  which the  routine must
  436.              start the search.
  437.     case   - See FirstOccurence.
  438.  
  439.   RESULT
  440.     found  reads  TRUE if  the  routine  has found the string looked for and
  441.     FALSE if not.  If  the  routine  returns  TRUE  the StringScan structure
  442.     contains the specific position where it has found the string.
  443.  
  444.   BUGS
  445.     None known.
  446.  
  447.   SEE ALSO
  448.     ascii.s/NextOccurrence(), ascii.s/PreviousOccurrence()
  449.     ascii.s/FirstOccurence()
  450.  
  451.